<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--

  	
 
  Copyright  2009  Sun Microsystems, Inc. All rights reserved.

-->
<HTML>
  <HEAD>
    <TITLE>MIDP MIDlet Lifecycle</TITLE>
    <META name="GENERATOR" content="StarOffice/5.1 (Win32)">
    <META name="CREATED" content="20000303;20101188">
    <META name="CHANGED" content="20000304;181548">
  </HEAD>
  <BODY>
    The MIDlet package defines Mobile Information
    Device Profile applications and the interactions between the
    application and the environment in which the application runs. An
    application of the Mobile Information Device Profile is a 
    <CODE>MIDlet</CODE>.
    <H2>Applications</H2>

    <P>
      The MIDP defines an application model to allow the limited resources of
      the device to be shared by multiple MIDP applications, or MIDlets. It
      defines what a MIDlet is, how it is packaged, what runtime environment
      is available to the MIDlet, and how it should be behave so that the
      device can manage its resources. The application model defines how
      multiple MIDlets forming a suite can be packaged together and share
      resources within the context of a single Java Virtual Machine. Sharing
      is feasible with the limited resources and security framework of the
      device since they are required to share class files and to be subject
      to a single set of policies and controls.</P>
    

    <H3>MIDP MIDlet Suite</H3>
    <P>
      A MIDP application MUST use only functionality specified by the MIDP
      specification as it is developed, tested, deployed, and run.</P>
    <P>
      The elements of a MIDlet suite are:</P>
    <UL>
      <LI>
        Runtime execution environment</LI>
      <LI>
        MIDlet suite packaging</LI>
      <LI>
        Application descriptor</LI>
      <LI>
        Application lifecycle</LI>
    </UL>
    <P>
      Each device is presumed to implement the functions required by its
      users to install, select, run, and remove MIDlets. The term application
      management software is used to refer collectively to these device
      specific functions. The application
      management software provides an environment in which the MIDlet is
      installed, started, stopped, and uninstalled. It is responsible for
      handling errors during the installation, execution, and removal of
      MIDlet suites and interacting with the user as needed. It provides to
      the MIDlet(s) the Java runtime environment required by the MIDP
      Specification.</P>
    <P>
      One or more MIDlets MAY be packaged in a single JAR file. Each MIDlet
      consists of a class that extends the <CODE>MIDlet</CODE>
      class and other classes as may be needed by the MIDlet.
      The manifest in the JAR file contains attributes that are used
      during installation and execution of MIDlets.
      The MIDlet is the entity that is launched
      by the application management software. When a MIDlet suite is
      invoked, a Java Virtual Machine is needed on which the classes can be
      executed. A new instance of the MIDlet is created by the application
      management software and used to direct the MIDlet to start, pause, and
      destroy itself. </P>
    <P>
      Sharing of data and other information between MIDlets is controlled by
      the individual APIs and their implementations. For example, the Record
      Management System API specifies the methods that are used when
      the record stores associated with a MIDlet suite are shared among
      MIDlets.</P>
    
    
    <H2>MIDlet Suite Security</H2>
    <P>The MIDP 1.0 specification constrained each MIDlet suite to
      operate in a sandbox wherein all of the APIs available to the
      MIDlets would prevent access to sensitive functions of the
      device.  That sandbox concept is used in this specification and
      all untrusted MIDlet suites are subject to its limitations.
      Every implementation of this specification MUST support running
      untrusted MIDlet suites. </P>

    <P>MIDP introduces the concept of trusted applications that
      may be permitted to use APIs that are considered sensitive and
      are restricted.  If and when a device determines that a MIDlet suite
      can be trusted the device allows access as indicated by the
      policy.
      <A HREF="doc-files/Authorization.html">Security for MIDP Applications</A>
      section describes the concepts and capabilities of untrusted and
      trusted applications.</P> 


    <H3>MIDP Execution Environment</H3>
    <P>
      The MIDP defines the execution environment provided to MIDlets. The
      execution environment is shared by all MIDlets within a MIDlet suite,
      and any MIDlet can interact with other MIDlets packaged together. The
      application management software initiates the applications and makes
      the following available to the MIDlet:</P>
    <UL>
      <LI>
        Classes and native code that implement the CLDC, including a Java
        Virtual Machine</LI>
      <LI>
        Classes and native code that implement the MIDP runtime</LI>
      <LI>
        All classes from a single JAR file for execution</LI>
      <LI>
        Non-class files from a single JAR file as resources</LI>
      <LI>
        Contents of the descriptor file, when it is present</LI>
      <li>
        Any other APIs available on the device such as implementations
        of additional JSRs, Licensee Open Classes, Optional Packages,
        etc.</li>
    </UL>
    <P>
      The CLDC and Java Virtual Machine provide multi-threading, locking and
      synchronization, the execution of byte codes, dispatching of methods,
      etc. A single VM is the scope of all policy, naming, and resource
      management. If a device supports multiple VMs, each may have its own
      scope, naming, and resource management policies. MIDlet Suites
      MUST NOT contain classes that are in packages defined by the
      CLDC or MIDP. </P>
    <P>
      The MIDP provides the classes that implement the MIDP APIs.
      The implementation MUST ensure that the application
      programmer cannot override, modify, or add any classes
      to these protected system packages.</P>
    <P>
      A single JAR file contains all of the MIDlet's classes. The MIDlet may
      load and invoke methods from any class in the JAR file, in the MIDP, or
      in the CLDC. All of the classes within these three scopes are shared in
      the execution environment of the MIDlets from the JAR file. All states
      accessible via those classes are available to any Java class running on
      behalf of the MIDlet. There is a single space containing the objects of
      all MIDlets, MIDP, and CLDC in use by the MIDlet suite. The usual Java
      locking and synchronization primitives SHOULD be used when necessary to
      avoid concurrency problems. Each library will specify how it handles
      concurrency and how the MIDlet should use it to run safely in a
      multi-threaded environment.</P>
    <P>
      The class files of the MIDlet are only available for execution and can
      neither be read as resources nor extracted for re-use. The
      implementation of the CLDC may store and interpret the contents of the
      JAR file in any manner suitable.</P>
    <P>
      The files from the JAR file that are not Java class files are made
      available using 
      <CODE>java.lang.Class.getResourceAsStream</CODE>.
      For example, the manifest would be available in this manner.</P>
    <P>
      The contents of the MIDlet descriptor file, when it is present, are made
      available via the
      <CODE>javax.microedition.midlet.MIDlet.getAppProperty</CODE> method.</P>
    
    
    <H3>MIDlet Suite Packaging</H3>
    <P>
      One or more MIDlets are packaged in a single JAR file that
      includes:</P>
    <UL>
      <LI>
        A manifest describing the contents</LI>
      <LI>
        Java classes for the MIDlet(s) and classes shared by the MIDlets</LI>
      <LI>
        Resource files used by the MIDlet(s)</LI>
    </UL>
    <P>
      The developer is responsible for creating and distributing the
      components of the JAR file as appropriate for the target user, device,
      network, locale, and jurisdiction. For example, for a particular
      locale, the resource files would be tailored to contain the strings and
      images needed for that locale.</P>
    <P>
      The JAR manifest defines attributes that are used by the application
      management software to identify and install the MIDlet suite and as
      defaults for attributes not found in the application descriptor. The
      attributes are defined for use in both the manifest and the optional
      application descriptor.</P>
    <P>
      The predefined attributes listed below allow the application management
      software to identify, retrieve, install, and invoke the MIDlet.</P>
   <TABLE BORDER="2">
      <H6>
        MIDlet Attributes</H6>
      <TR>
        <TH ROWSPAN="1" COLSPAN="1">
          <P>
            Attribute Name </P>
        </TH>
        <TH ROWSPAN="1" COLSPAN="1">
          <P>
            Attribute Description</P>
        </TH>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Name</P>
          <P>
            &nbsp;</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The name of the MIDlet suite that identifies the MIDlets to the
            user.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Version</P>
          <P>
            &nbsp;</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The version number of the MIDlet suite. Version numbers
            are <A HREF="#vernum">formatted</A> so they can be used by
            the application management software for install and
            upgrade uses, as well as communication with the user.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Vendor</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The organization that provides the MIDlet suite.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Icon</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The case-sensitive absolute name of a PNG file within the
            JAR used to represent the MIDlet
            suite. It SHOULD be used when the Application Management Software
            displays an icon to identify the suite.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Description</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The description of the MIDlet suite.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Info-URL</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            A URL for information further describing the MIDlet suite.
            The syntax and meaning MUST conform to RFC2396 and RFCs that
            define each scheme.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-&lt;n&gt;</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The name, icon, and class of the nth MIDlet in the JAR file separated
            by a comma. The lowest value of &lt;n&gt; MUST be 1 and consecutive
            originals MUST be used. 
	    The first missing entry terminates the list.
	    Any additional entries are ignored.
	    Leading and trailing spaces in
            name, icon and class are ignored.  
	  </P>
          <OL>
            <LI>
              Name is used to identify this MIDlet to the user.
              The name must be present and be non-null.</LI>
            <LI>
              Icon is the case-sensitive absolute path name of an
              image (PNG) within the JAR for the icon of the nth
              MIDlet.  The icon may be omitted.</LI>
            <LI>
              Class is the name of the class extending the
              <CODE>javax.microedition.midlet.MIDlet</CODE> class for
              the nth MIDlet. The classname MUST be non-null and
              contain only characters for Java class names.  The class
              MUST have a public no-args constructor. The class name
              IS case sensitive.</LI>
          </OL>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Jar-URL</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The URL from which the JAR file can be loaded.  The syntax
            and meaning MUST conform to RFC2396 and RFCs that define
            each scheme. Both absolute and relative URLs MUST be
            supported. The context for a relative URL is the URL from
            which this application descriptor was loaded.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Jar-Size</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The number of bytes in the JAR file.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MIDlet-Data-Size</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The minimum number of bytes of persistent data required by the MIDlet.
            The device may provide additional storage according to its own policy.
            The default is zero.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MicroEdition-Profile</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>The J2ME profiles required, using the same format and
          value as the System property
          <CODE>microedition.profiles</CODE> (for example "MIDP-2.1").
          The device must implement <EM>all</EM> of the profiles
          listed.  If any of the profiles are not implemented the
          installation MUST fail.  Multiple profiles are separated
          with a blank (Unicode U+0020).</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            MicroEdition-Configuration</P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            The J2ME Configuration required using the same format and value as the
            System property <CODE>microedition.configuration</CODE>
            (for example &quot;CLDC-1.0&quot;).</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Permissions
            </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>Zero or more permissions that are critical to the function
            of the MIDlet suite.
            See the <A HREF="doc-files/Authorization.html">MIDlet Suite
            Security</A> section for details of usage.
          </P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Permissions-Opt
            </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>Zero or more permissions that are non-critical to the
            function of the MIDlet suite.
            See the <A HREF="doc-files/Authorization.html">MIDlet Suite
            Security</A> section for details of usage.
          </P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Push-&lt;n&gt;
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            Register a MIDlet to handle inbound connections.
            Refer to <A HREF="../io/PushRegistry.html">
              javax.microedition.io.PushRegistry</A> for details.
          </P>
        </TD>
      </TR>

      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Install-Notify
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>Refer to the <A HREF="../../../../OTASpecification.html#AdditionalAttributes">
                        OTA Specification</A> for details.
          </P>
        </TD>
      </TR>

      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Delete-Notify
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>Refer to the <A HREF="../../../../OTASpecification.html#AdditionalAttributes">
                        OTA Specification</A> for details.
          </P>
        </TD>
      </TR>

      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>MIDlet-Delete-Confirm
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>Refer to the <A HREF="../../../../OTASpecification.html#AdditionalAttributes">
                        OTA Specification</A> for details.
          </P>
        </TD>
      </TR>

    </TABLE>

   <P>
     Some attributes use multiple values, for those attributes the
     values are separated by a comma (Unicode U+002C) except where noted.
     Leading and trailing whitespace (Unicode U+0020) and tab
     (Unicode U+0009) are ignored on each value. </P>


    <H4><A NAME="vernum">Version Numbering</A></H4>
    <P>
      Version numbers have the format Major.Minor[.Micro] (X.X[.X]), where
      the .Micro portion MAY be omitted. (If the .Micro portion is not
      omitted, then it defaults to zero). In addition, each portion of the
      version number is allowed a maximum of two decimal digits (i.e.,
      0-99).
      Version numbers are described in the
      the Java(TM) Product Versioning Specification
      <A HREF="http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html">
        http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html</A>.</P>
    <P>
      For example, 1.0.0 can be used to specify the first version of a MIDlet
      suite. For each portion of the version number, leading zeros are not
      significant. For example, 08 is equivalent to 8. Also, 1.0 is
      equivalent to 1.0.0. However, 1.1 is equivalent to 1.1.0, and not
      1.0.1.</P>
    <P>
      A missing MIDlet-Version tag is assumed to be 0.0.0, which means that
      any non-zero version number is considered as a newer version of the
      MIDlet suite.</P>
    
    <H4>JAR Manifest</H4>
    <P>
      The manifest provides information about the contents of the JAR file.
      JAR file formats and specifications are available at 
      <A
        HREF="http://java.sun.com/products/jdk/1.2/docs/guide/jar/index.html">
        http://java.sun.com/products/jdk/1.2/docs/guide/jar/index.html.</A>
      Refer to the JDK JAR and manifest documentation for the syntax and
      related details. MIDP implementations MUST implement handling of
      lines longer than 72 bytes as defined in the manifest
      specification.
      An attribute MUST not appear more than once within the manifest.
      If an attribute is duplicated the effect is unspecified.
      Manifest attributes are passed to the MIDlet when requested
      using the <CODE>MIDlet.getAppProperty</CODE> method, unless the
      attribute is duplicated in the application descriptor, for
      handling of duplicate attributes see the "Application
      Descriptor" section.</P>

    <P>
      The manifest MUST contain the following attributes:</P>
    <UL>
      <LI>
        MIDlet-Name</LI>
      <LI>
        MIDlet-Version</LI>
      <LI>
        MIDlet-Vendor</LI>
    </UL>
    <P>
      The manifest or the application descriptor MUST contain the following
      attributes:</P>
    <UL>
      <LI>
        MIDlet-&lt;n&gt; for each MIDlet</LI>
      <LI>
        MicroEdition-Profile</LI>
      <LI>
        MicroEdition-Configuration</LI>
    </UL>
    <P>
      The manifest MAY contain the following:</P>
    <UL>
      <LI>
        MIDlet-Description</LI>
      <LI>
        MIDlet-Icon</LI>
      <LI>
        MIDlet-Info-URL</LI>
      <LI>
        MIDlet-Data-Size</LI>
      <LI>
        MIDlet-Permissions </LI>
      <LI>
        MIDlet-Permissions-Opt </LI>
      <LI>
	MIDlet-Push-&lt;n&gt;</LI>
      <LI>
        MIDlet-Install-Notify</LI>
      <LI>
        MIDlet-Delete-Notify</LI>
      <LI>
        MIDlet-Delete-Confirm </LI>
      <LI>
	Any application-specific attributes that do not begin with
	<CODE>MIDlet-</CODE> or <CODE>MicroEdition-</CODE></LI>
    </UL>

    <P>
      For example, a manifest for a hypothetical suite of card games would
      look like the following example:</P>
    <TABLE BORDER="2" width="400">
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <pre><code>
  MIDlet-Name: CardGames    
  MIDlet-Version: 1.1.9    
  MIDlet-Vendor: CardsRUS    
  MIDlet-1: Solitaire, /Solitare.png, org.cardsrus.games.Solitare     
  MIDlet-2: JacksWild, /JacksWild.png, org.cardsrus.games.JacksWild     
  MicroEdition-Profile: MIDP-2.1
  MicroEdition-Configuration: CLDC-1.0     
  Solitaire-Author: John Q. Public      </CODE></PRE>
        </TD>
      </TR>
    </TABLE>
    
    
    <H4> MIDlet Classes</H4>
    <P>
      All Java classes needed by the MIDlet are be placed in the JAR file
      using the standard structure, based on mapping the fully qualified
      class names to directory and file names. Each period is converted to a
      forward slash ( / ) and the <CODE>.class</CODE>
      extension is appended. For example, a class 
      <CODE>com.sun.microedition.Test</CODE>
      would be placed in the JAR file with the name 
      <CODE>com/sun/microedition/Test.class</CODE>
      .</P>
    
    
    
    <H3>Application Descriptor</H3>
    <P>
      Each JAR file MAY be accompanied by an application descriptor. 
      The application descriptor is used in conjunction with the JAR
      manifest by the application management software to manage the MIDlet and
      is used by the MIDlet itself for configuration specific attributes. The
      descriptor allows the application management software on the device to
      verify that the MIDlet is suited to the device before loading the full
      JAR file of the MIDlet suite. It also allows configuration-specific
      attributes (parameters) to be supplied to the MIDlet(s) without
      modifying the JAR file.</P>
    <P>
      To allow devices to dispatch an application descriptor to the MIDP
      application management software, a file extension and
      <A HREF="http://www.iana.org/assignments/media-types/text/vnd.sun.j2me.app-descriptor">
        MIME type</A> are registered with the IANA:</P>
    <UL>
      <LI>
        The file extension of an application descriptor file is
        <CODE>jad</CODE>
      </LI>
      <LI>
        The MIME type of an application descriptor file is <BR>
        <CODE>text/vnd.sun.j2me.app-descriptor</CODE>.
      </LI>
    </UL>
    
    <P>
      A predefined set of attributes is
      specified to allow the application management software to identify,
      retrieve, and install the MIDlet(s). All attributes appearing in the
      descriptor file are made available to the MIDlet(s). The developer may
      use attributes not beginning with <CODE>MIDlet-</CODE> or
      <CODE>MicroEdition-</CODE> for
      application-specific purposes.
      Attribute names are case-sensitive and MUST match exactly.
      An attribute MUST NOT appear more than once within the manifest.
      If an attribute is duplicated the effect is unspecified.
      The MIDlet retrieves attributes by name by calling the
      <CODE>MIDlet.getAppProperty</CODE>  method.

</P>

    <P>
      The application descriptor MUST contain the following attributes:</P>
    <UL>
      <LI>
        MIDlet-Name</LI>
      <LI>
        MIDlet-Version</LI>
      <LI>
        MIDlet-Vendor</LI>
      <LI>
        MIDlet-Jar-URL</LI>
      <LI>
        MIDlet-Jar-Size</LI>
    </UL>
    <P>
      The application descriptor MAY contain:</P>
    <UL>
      <LI>
        MIDlet-&lt;n&gt; for each MIDlet</LI>
      <LI>
        MicroEdition-Profile</LI>
      <LI>
        MicroEdition-Configuration</LI>
      <LI>
        MIDlet-Description</LI>
      <LI>
        MIDlet-Icon</LI>
      <LI>
        MIDlet-Info-URL</LI>
      <LI>
        MIDlet-Data-Size</LI>
      <LI>
	MIDlet-Permissions </LI>
      <LI>
	MIDlet-Permissions-Opt </LI>
      <LI>
	MIDlet-Push-&lt;n&gt;</LI>
      <LI>
        MIDlet-Install-Notify</LI>
      <LI>
        MIDlet-Delete-Notify</LI>
      <LI>
        MIDlet-Delete-Confirm </LI>
      <LI>
        Any application-specific attributes that do not begin with
	<CODE>MIDlet-</CODE> or <CODE>MicroEdition-</CODE></LI>
    </UL>

    <P>
      The mandatory attributes MIDlet-Name, MIDlet-Version, and MIDlet-Vendor
      MUST be duplicated in the descriptor and manifest files since they
      uniquely identify the application. If they are
      not identical (not from the same application), then the JAR MUST NOT be
      installed. </P>
    <P>Duplication of other manifest attributes in the application
      descriptor is not required and their 
      values MAY differ even though both the manifest and descriptor files
      contain the same attribute for
      <A HREF="doc-files/Authorization.html#untrusted">untrusted</A>
      MIDlet suites. 
      If the MIDlet suite is not trusted the value from the descriptor
      file will override the value from the manifest file.
      If the MIDlet suite is
      <A HREF="doc-files/Authorization.html#trusted">trusted</A>
      then the values in the application descriptor 
      MUST be identical to the corresponding attribute values in the Manifest.
    </P>
    <P>
      MIDlets MUST NOT add any attributes to the manifest or the
      Application Descriptor that start with <CODE>MIDlet-</CODE> or
      <CODE>MicroEdition-</CODE> other than those defined in the relevant
      Configuration and Profiles (e.g. CLDC and MIDP) specifications.
      Unrecognized attributes MUST be ignored by the AMS.</P>
    <P>
      Generally speaking, the format of the application descriptor is a
      sequence of lines consisting of an attribute name followed by a colon,
      the value of the attribute, and a carriage return. White space is
      ignored before and after the value. The order of the attributes is
      arbitrary.</P>
    <P>
      The application descriptor MAY be encoded for transport or storage and
      MUST be converted to Unicode before parsing, using the rules below. For
      example, an ISO-8859-1 encoded file would need to be read through the
      equivalent of <CODE>java.io.InputStreamReader</CODE>
      with the appropriate encoding. The default character encoding for 
      transporting a descriptor is UTF-8. Descriptors retrieved via HTTP,
      if that is supported, SHOULD use the standard HTTP content negotiation
      mechanisms, such as the Content-Encoding header and the Content-Type
      charset parameter to convert the stream to UCS-2.</P>
    
    <EM>
      BNF for Parsing Application Descriptors</EM>
    <TABLE BORDER="2" width="400">
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <PRE><CODE>
 appldesc:  *attrline    
 attrline:  attrname &quot;:&quot; [WSP] attrvalue [WSP] newlines
 attrname:  1*&lt;any Unicode char except 
                 CTLs or separators&gt;    
 attrvalue: *valuechar | valuechar *(valuechar | WSP) valuechar    
 valuechar: &lt;any valid Unicode character, 
            excluding CTLS and WSP&gt;    
 newlines = 1*newline  ; allow blank lines to be ignored
 newline:   CR LF | LF 
   
 CR  = &lt;Unicode carriage return (U+000D)&gt;     
 LF  = &lt;Unicode linefeed (U+000A)&gt;     
 
 WSP:  1*( SP | HT )
 SP  = &lt;Unicode space (U+0020)&gt;
 HT  = &lt;Unicode horizontal-tab (U+0009)&gt;
 CTL = &lt;Unicode characters 
           U+0000 - U+001F and U+007F&gt;
 separators: &quot;(&quot; | &quot;)&quot; | &quot;&lt;&quot; |    
             &quot;&gt;&quot; | &quot;@&quot; |   
             &quot;,&quot; | &quot;;&quot; | &quot;:&quot; |    
             &quot;'&quot; | &lt;&quot;&gt;|    
             &quot;/&quot; | &quot;[&quot; | &quot;]&quot; |    
             &quot;?&quot; | &quot;=&quot; |        
             &quot;{&quot; | &quot;}&quot; | SP | HT            </CODE></PRE></TD>
      </TR>
    </TABLE>
    <P>
      For example, an application descriptor for a hypothetical suite of card
      games would look look like the following example:</P>
    <TABLE BORDER="2" width="400">
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
<PRE><CODE>
 MIDlet-Name: CardGames    
 MIDlet-Version: 1.1.9    
 MIDlet-Vendor: CardsRUS    
 MIDlet-1: Solitaire, /Solitare.png, com.cardsrus.org.Solitare     
 MIDlet-2: JacksWild, /JacksWild.png, com.cardsrus.org.JacksWild     
 MicroEdition-Profile: MIDP-2.1    
 MicroEdition-Configuration: CLDC-1.0    
 MIDlet-Description: Really cool card games    
 MIDlet-Jar-URL: http://www.cardsrus.com/games/cardgames.jar    
 MIDlet-Jar-Size: 7378    
 MIDlet-Data-Size: 256     </CODE></PRE>
        </TD>
      </TR>
    </TABLE>
    
    
    
    <H3>Application Lifecycle</H3>
    <P>
      Each MIDlet MUST extend the <CODE>MIDlet</CODE>
      class. The <CODE>MIDlet</CODE>
      class allows for the orderly starting, stopping, and cleanup of the
      MIDlet. The MIDlet can request the arguments from the application
      descriptor to communicate with the application management software. A
      MIDlet suite MUST NOT have a <CODE>public static void main()</CODE>
      method. If it exists, it MUST be ignored by the application management
      software. The application management software provides the initial
      class needed by the CLDC to start a MIDlet.</P>
    <P>
      When a MIDlet suite is installed on a device, its classes, resource
      files, arguments, and persistent storage are kept on the device and
      ready for use. The MIDlet(s) are available to the user via the device's
      application management software.</P>
    <P>
      When the MIDlet is run, an instance of the MIDlet's primary class is
      created using its public no-argument constructor, and the methods of
      the <CODE>MIDlet</CODE>
      are called to sequence the MIDlet through its various states. The
      MIDlet can either request changes in state or notify the application
      management software of state changes via the <CODE>MIDlet</CODE>
      methods. When the MIDlet is finished or terminated by the application
      management software, it is destroyed, and the resources it used can be
      reclaimed, including any objects it created and its classes. The
      MIDlet MUST NOT call <CODE>System.exit</CODE>
      , which will throw a <CODE>SecurityException</CODE>
      when called by a MIDlet.</P>
    <P>
      The normal states of Java classes are not affected by these classes as
      they are loaded. Referring to any class will cause it to be loaded, and
      the normal static initialization will occur.</P>
    <TABLE BORDER="2">
      <TR>
        <TH ROWSPAN="1" COLSPAN="1">
          Class in
          <CODE>javax.microedition.midlet</CODE>
        </TH>
        <TH ROWSPAN="1" COLSPAN="1">
          Description
        </TH>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            <CODE>MIDlet</CODE>
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            Extended by a MIDlet to allow the application management software to
            start, stop, and destroy it.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            <CODE>MIDletStateChangeException</CODE>
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            Thrown when the application cannot make the change requested.</P>
        </TD>
      </TR>
    </TABLE>
    <H3>MIDlet lifecycle</H3>
    
    <P align="LEFT">The <CODE>MIDlet</CODE> lifecycle defines the
      protocol between a <CODE>MIDlet</CODE> and its environment through
      the following:</P>

    <UL>
      <LI>
        <P>A simple well-defined state machine</P>
      </LI>

      <LI>
        <P>A concise definition of the MIDlet's states</P>
      </LI>

      <LI>
        <P>APIs to signal changes between the states</P>
      </LI>
    </UL>

    <H2>MIDlet Lifecycle Definitions</H2>

    <P>The following definitions are used in the <CODE>MIDlet</CODE>
      lifecycle:</P>

    <UL>
      <LI>
        <P><A name="appMgrDefined"></A>
          <B>application management software
            -</B> a part of the device's software operating environment that
          manages <CODE>MIDlets</CODE>. It maintains the MIDlet state
          and directs the <CODE>MIDlet</CODE>
          through state changes.</P>
      </LI>

      <LI>
        <P><CODE><B>MIDlet</B></CODE> - a MIDP application on the device.
          The <CODE>MIDlet</CODE> can signal the application management
          software about whether is it wants to run or has completed. A
          <CODE>MIDlet</CODE> has no knowledge of other <CODE>MIDlet</CODE>s
          through the <CODE>MIDlet</CODE> API.</P>
      </LI>

      <LI>
        <P><B><CODE>MIDlet</CODE> States</B> - the states a 
          <CODE>MIDlet</CODE> can have are defined by the transitions allowable
          through the <CODE>MIDlet</CODE> interface. More specific
          application states are known only to the application.</P>
      </LI>
    </UL>

    <H2>MIDlet States</H2>

    <P>The <CODE>MIDlet</CODE> state machine is designed to ensure that
      the behavior of an application is consistent and as close as
      possible to what device manufactures and users expect,
      specifically:</P>

    <UL>
      <LI>
        <P>The perceived startup latency of an application SHOULD be very
          short.</P>
      </LI>

      <LI>
        <P>It SHOULD be possible to put an application into a state where
          it is not active.</P>
      </LI>

      <LI>
        <P>It SHOULD be possible to destroy an application at any time.</P>
      </LI>
    </UL>

    <P style="margin-bottom: 0in">The valid states for
      <CODE>MIDlet</CODE>s are:</P>

    <TABLE width="100%" border="2" cellpadding="2" cellspacing="3">
     <TR>
        <TH width="20%">
          State Name
        </TH>
        <TH width="80%">
          Description
        </TH>
      </TR>

      <TR>
        <TD width="20%">
          <P>Paused</P>
        </TD>
        <TD width="80%">
          <P>The <CODE>MIDlet</CODE> is initialized and is quiescent. It
            SHOULD not be holding or using any shared resources. This state is
            entered:</P>

          <UL>
            <LI>
              <P>After the <CODE>MIDlet</CODE> has been created using
                <CODE>new</CODE>. The public no-argument constructor for the 
                <CODE>MIDlet</CODE> is called and returns without throwing an exception.
                The application typically does little or no initialization in this
                step. If an exception occurs, the application immediately enters
                the Destroyed state and is discarded.</P>
            </LI>
          </UL>

          <UL>
            <LI>
              <P>From the Active state after the
              <CODE>MIDlet.pauseApp()</CODE> method is called from the
              AMS and returns successfully.</P>
            </LI>

            <LI>
              <P>From the Active state when the 
                <CODE>MIDlet.notifyPaused()</CODE> method returns successfully to the
                <CODE>MIDlet</CODE>.</P>
            </LI>

            <LI>
              <P>From the Active state if <CODE>startApp</CODE> throws an 
                <CODE>MIDletStateChangeException</CODE>.</P>
            </LI>
          </UL>
        </TD>
      </TR>

      <TR>
        <TD width="20%">
          <P>Active</P>
        </TD>
        <TD width="80%">
          <P>The <CODE>MIDlet</CODE> is functioning normally. This state is
            entered:</P>

          <UL>
            <LI>
              <P>Just prior to the AMS calling the
              <CODE>MIDlet.startApp()</CODE> method.</P>
            </LI>
          </UL>
        </TD>
      </TR>

      <TR>
        <TD width="20%">
          <P>Destroyed</P>
        </TD>
        <TD width="80%">
          <P>The <CODE>MIDlet</CODE> has released all of its resources and
            terminated. This state is entered:</P>

          <UL>
            <LI>
              <P>When the AMS called the
              <CODE>MIDlet.destroyApp()</CODE> method and returns
              successfully, except in the case when the
              <CODE>unconditional</CODE> argument is false and a
              <CODE>MIDletStateChangeException</CODE> is thrown. The
              <CODE>destroyApp()</CODE> method shall release all
              resources held and perform any necessary cleanup so it
              may be garbage collected.</P>
            </LI>

            <LI>
              <P>When the <CODE>MIDlet.notifyDestroyed()</CODE> method returns
                successfully to the application. The <CODE>MIDlet</CODE> must have
                performed the equivalent of the <CODE>MIDlet.destroyApp()</CODE>
                method before calling <CODE>MIDlet.notifyDestroyed()</CODE>.</P>
            </LI>
          </UL>

          <P><B>Note:</B> This state is only entered once.</P>
        </TD>
      </TR>
    </TABLE>

    <P><BR>
      <BR>
    </P>

    <P>The states and transitions for a <CODE>MIDlet</CODE> are:</P>

    <P><IMG src="doc-files/App-States.gif" name="Graphic1" align="LEFT"
             width=377 height=309 border="0"><BR clear="LEFT">
      <BR>
      <BR>
    </P>

    <H2>MIDlet Lifecycle Model</H2>

    <P style="margin-bottom: 0in">A typical sequence of 
      <CODE>MIDlet</CODE> execution is:</P>
    
    <TABLE width="100%" border="2" cellpadding="2" cellspacing="3">
       <TR>
        <TH width="66%">
          Application Management Software
        </TH>
        <TH width="34%">
          <CODE>MIDlet</CODE>
        </TH>
      </TR>

      <TR>
        <TD width="66%">
          <P>The application management software creates a new instance of a
            <CODE>MIDlet</CODE>.</P>
        </TD>
        <TD width="34%">
          <P>The default (no argument) constructor for the 
            <CODE>MIDlet</CODE> is called; it is in the Paused state.</P>
        </TD>
      </TR>

      <TR>
        <TD width="66%">
          <P>The application management software has decided that it is an
            appropriate time for the <CODE>MIDlet</CODE> to run, so it calls
            the <CODE>MIDlet.startApp</CODE> method for it to enter the Active
            state.</P>
        </TD>
        <TD width="34%">
          <P>The <CODE>MIDlet</CODE> acquires any resources it needs and
            begins to perform its service.</P>
        </TD>
      </TR>

      <TR>
        <TD width="66%">
          <P>The application management software wants the MIDlet to
	    significantly reduce the amount of resources it is
	    consuming, so that they may temporarily be used by other
	    functions on the device such as a phone call or running
	    another MIDlet. The AMS will signal this request to the
	    MIDlet by calling the <CODE>MIDlet.pauseApp</CODE>
	    method. The MIDlet should then reduce its resource
	    consumption as much as possible.</P>
        </TD>
        <TD width="34%">
          <P>The <CODE>MIDlet</CODE> stops performing its service and might
            choose to release some resources it currently holds.</P>
        </TD>
      </TR>

      <TR>
        <TD width="66%">
          <P>The application management software has determined that the
            <CODE>MIDlet</CODE> is no longer needed, or perhaps needs to make
            room for a higher priority application in memory, so it signals the
            <CODE>MIDlet</CODE> that it is a candidate to be destroyed by
            calling the <CODE>MIDlet.destroyApp</CODE> method.</P>
        </TD>
        <TD width="34%">
          <P>If it has been designed to do so, the <CODE>MIDlet</CODE> saves
            state or user preferences and performs clean up.</P>
        </TD>
      </TR>
    </TABLE>

    <H2>MIDlet Interface</H2>

    <UL>
      <LI>
        <P><CODE>pauseApp</CODE> - the <CODE>MIDlet</CODE> SHOULD release
          any temporary resources and become passive</P>
      </LI>

      <LI>
        <P><CODE>startApp</CODE> - the <CODE>MIDlet</CODE>
          SHOULD acquire any resources it needs and resume</P>
      </LI>

      <LI>
        <P><CODE>destroyApp</CODE> - the <CODE>MIDlet</CODE> SHOULD save
          any state and release all resources</P>
      </LI>

      <LI>
        <P><CODE>notifyDestroyed</CODE> - the <CODE>MIDlet</CODE> notifies
          the application management software that it has cleaned up and is
          done</P>
      </LI>

      <LI>
        <P><CODE>notifyPaused</CODE> - the <CODE>MIDlet</CODE> notifies the
          application management software that it has paused</P>
      </LI>

      <LI>
        <P><CODE>resumeRequest</CODE> - the <CODE>MIDlet</CODE> asks
          application management software to be started again</P>
      </LI>

      <LI>
        <P><CODE>getAppProperty</CODE> - gets a named property from the
          <CODE>MIDlet</CODE></P>
      </LI>
    </UL>

    <H2>Application Implementation Notes</H2>

    <P>The application SHOULD take measures to avoid race conditions in
      the execution of the <CODE>MIDlet</CODE> methods. Each method may
      need to synchronize itself with the other methods avoid concurrency
      problems during state changes.</P>

    <H2>Example MIDlet Application</H2>

    <P>The example uses the MIDlet lifecycle to do a simple measurement
      of the speed of the Java Virtual Machine.</P>

<PRE><CODE>
import javax.microedition.midlet.*;      
      
/**      
 * An example MIDlet runs a simple timing test      
 * When it is started by the application management software it will      
 * create a separate thread to do the test.      
 * When it finishes it will notify the application management software      
 * it is done.      
 * Refer to the startApp, pauseApp, and destroyApp      
 * methods so see how it handles each requested transition.      
 */      
public class MethodTimes extends MIDlet implements Runnable {      
    // The state for the timing thread.      
    Thread thread;      
      
    /**      
     * Start creates the thread to do the timing.      
     * It should return immediately to keep the dispatcher      
     * from hanging.      
     */      
    public void startApp() {      
        thread = new Thread(this);      
        thread.start();      
    }      
      
    /**      
     * Pause signals the thread to stop by clearing the thread field.      
     * If stopped before done with the iterations it will      
     * be restarted from scratch later.      
     */      
    public void pauseApp() {      
        thread = null;      
    }      
      
    /**      
     * Destroy must cleanup everything.  The thread is signaled      
     * to stop and no result is produced.      
     */      
    public void destroyApp(boolean unconditional) {      
        thread = null;      
    }      
      
   /**      
     * Run the timing test, measure how long it takes to      
     * call a empty method 1000 times.      
     * Terminate early if the current thread is no longer      
     * the thread from the      
     */      
    public void run() {      
        Thread curr = Thread.currentThread();  // Remember which thread is current      
        long start = System.currentTimeMillis();      
        for (int i = 0; i &lt; 1000000 &amp;&amp; thread == curr; i++) {      
            empty();      
        }      
        long end = System.currentTimeMillis();      
      
        // Check if timing was aborted, if so just exit      
        // The rest of the application has already become quiescent.      
        if (thread != curr) {      
            return;      
        }      
        long millis = end - start;      
        // Reporting the elapsed time is outside the scope of this example.      
      
        // All done cleanup and quit      
        destroyApp(true);      
        notifyDestroyed();      
    }      
      
    /**      
     * An Empty method.      
     */      
    void empty() {      
    }      
}     </code></PRE>
@since MIDP 1.0
</BODY>
</HTML>

